home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 7 / Amiga Format AFCD07 (Dec 1996, Issue 91).iso / serious / shareware / programming / ixemul-complete / ixemul / man / man3 / intro.3 < prev    next >
Text File  |  1996-05-08  |  7KB  |  229 lines
  1. .\" Copyright (c) 1980, 1993
  2. .\"    The Regents of the University of California.  All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms, with or without
  5. .\" modification, are permitted provided that the following conditions
  6. .\" are met:
  7. .\" 1. Redistributions of source code must retain the above copyright
  8. .\"    notice, this list of conditions and the following disclaimer.
  9. .\" 2. Redistributions in binary form must reproduce the above copyright
  10. .\"    notice, this list of conditions and the following disclaimer in the
  11. .\"    documentation and/or other materials provided with the distribution.
  12. .\" 3. All advertising materials mentioning features or use of this software
  13. .\"    must display the following acknowledgement:
  14. .\"    This product includes software developed by the University of
  15. .\"    California, Berkeley and its contributors.
  16. .\" 4. Neither the name of the University nor the names of its contributors
  17. .\"    may be used to endorse or promote products derived from this software
  18. .\"    without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\"    @(#)intro.3    8.1 (Berkeley) 6/4/93
  33. .\"
  34. .sh 1 Usage
  35. .pp
  36. This is a description of how to actually use the screen package.
  37. For simplicity, we assume all updating, reading, etc.
  38. is applied to
  39. .Vn stdscr , 
  40. although a different window can of course be specified.
  41. .sh 2 "Initialization"
  42. .pp
  43. In order to use the screen package,
  44. the routines must know about terminal characteristics,
  45. and the space for
  46. .Vn curscr
  47. and
  48. .Vn stdscr
  49. must be allocated.
  50. These functions are performed by
  51. .Fn initscr .
  52. Since it must allocate space for the windows,
  53. it can overflow core when attempting to do so.
  54. On this rather rare occasion,
  55. .Fn initscr
  56. returns ERR.
  57. .Fn Initscr
  58. must
  59. .bi always
  60. be called before any of the routines which affect windows are used.
  61. If it is not,
  62. the program will core dump as soon as either
  63. .Vn curscr
  64. or
  65. .Vn stdscr
  66. are referenced.
  67. However, it is usually best to wait to call it
  68. until after you are sure you will need it,
  69. like after checking for startup errors.
  70. Terminal status changing routines
  71. like
  72. .Fn nl
  73. and
  74. .Fn cbreak
  75. should be called after
  76. .Fn initscr .
  77. .pp
  78. After the initial window allocation done by 
  79. .Fn initscr ,
  80. specific window characteristics can be set.
  81. Scrolling can be enabled by calling
  82. .Fn scrollok .
  83. If you want the cursor to be left after the last change, use
  84. .Fn leaveok .
  85. If this isn't done,
  86. .Fn refresh
  87. will move the cursor to the window's current \*y after updating it.
  88. Additional windows can be created by using the functions
  89. .Fn newwin
  90. and
  91. .Fn subwin .
  92. .Fn Delwin
  93. allows you to delete an exisiting window.
  94. The variables
  95. .Vn LINES
  96. and
  97. .Vn COLS
  98. control the size of the terminal.  They are initially implicitly set by 
  99. .Fn initscr ,
  100. but can be altered explicitly by the user followed by a call to 
  101. .Fn initscr .
  102. Note that any call to 
  103. .Fn initscr ,
  104. will always delete any existing
  105. .Vn stdscr
  106. and/or
  107. .Vn curscr
  108. before creating new ones so this change is best done before the initial call to
  109. .Fn initscr .
  110. .pp
  111. .sh 2 "Output"
  112. .pp
  113. The basic functions
  114. used to change what will go on a window are
  115. .Fn addch
  116. and
  117. .Fn move .
  118. .Fn Addch
  119. adds a character at the current \*y,
  120. returning ERR if it would cause the window to illegally scroll,
  121. .i i.e. ,
  122. printing a character in the lower right-hand corner
  123. of a terminal which automatically scrolls
  124. if scrolling is not allowed.
  125. .Fn Move
  126. changes the current \*y to whatever you want them to be.
  127. It returns ERR if you try to move off the window.
  128. As mentioned above, you can combine the two into
  129. .Fn mvaddch
  130. to do both things in one call.
  131. .pp
  132. The other output functions 
  133. (such as
  134. .Fn addstr
  135. and
  136. .Fn printw )
  137. all call
  138. .Fn addch
  139. to add characters to the window.
  140. .pp
  141. After a change has been made to the window,
  142. you must call 
  143. .Fn refresh .
  144. when you want the portion of the terminal covered by the window
  145. to reflect the change.
  146. In order to optimize finding changes,
  147. .Fn refresh
  148. assumes that any part of the window not changed
  149. since the last
  150. .Fn refresh
  151. of that window has not been changed on the terminal,
  152. .i i.e. ,
  153. that you have not refreshed a portion of the terminal
  154. with an overlapping window.
  155. If this is not the case,
  156. the routines
  157. .Fn touchwin ,
  158. .Fn touchline ,
  159. and
  160. .Fn touchoverlap
  161. are provided to make it look like a desired part of window has been changed,
  162. thus forcing
  163. .Fn refresh
  164. to check that whole subsection of the terminal for changes.
  165. .pp
  166. If you call
  167. .Fn wrefresh
  168. with
  169. .Vn curscr ,
  170. it will make the screen look like the image of 
  171. .Vn curscr .
  172. This is useful for implementing a command
  173. which would redraw the screen in case it got messed up.
  174. .sh 2 Input
  175. .pp
  176. Input is essentially a mirror image of output.
  177. The complementary function to
  178. .Fn addch
  179. is
  180. .Fn getch
  181. which,
  182. if echo is set,
  183. will call
  184. .Fn addch
  185. to echo the character.
  186. Since the screen package needs to know what is on the terminal at all times,
  187. if characters are to be echoed,
  188. the tty must be in raw or cbreak mode.
  189. If it is not,
  190. .Fn getch
  191. sets it to be cbreak,
  192. and then reads in the character.
  193. .sh 2 "Termination"
  194. .pp
  195. In order to perform certain optimizations,
  196. and, 
  197. on some terminals,
  198. to work at all,
  199. some things must be done
  200. before the screen routines start up.
  201. These functions are performed in
  202. .Fn getttmode
  203. and
  204. .Fn setterm ,
  205. which are called by
  206. .Fn initscr .
  207. In order to clean up after the routines,
  208. the routine
  209. .Fn endwin
  210. is provided.
  211. It restores tty modes to what they were
  212. when
  213. .Fn initscr
  214. was first called.
  215. The terminal state module uses the variable 
  216. .Vn curses_termios
  217. to save the original terminal state which is then restored upon a call to 
  218. .Fn endwin .
  219. Thus,
  220. anytime after the call to initscr,
  221. .Fn endwin
  222. should be called before exiting.  Note however, that 
  223. .Fn endwin 
  224. should always be called 
  225. .b before
  226. the final calls to
  227. .Fn delwin ,
  228. which free the storage of the windows.
  229.